---
title: 국제화 (i18n) 라우팅
sidebar:
  label: 국제화 (i18n)
description: Astro의 i18n 라우팅 기능을 사용하여 사이트의 페이지를 현지화하는 방법을 알아보세요.
i18nReady: true
---

import { FileTree } from '@astrojs/starlight/components';
import Since from '~/components/Since.astro';

Astro의 국제화 (i18n) 기능을 사용하면 전 세계의 방문자들을 대상으로 프로젝트를 조정할 수 있습니다. 이 라우팅 API는 다국어 사이트가 생성하는 URL을 생성, 사용 및 확인하는 데 도움이 됩니다.

Astro의 i18n 라우팅을 사용하면 기본 언어 구성, 관련 페이지 URL 계산, 방문자 브라우저에서 제공하는 기본 언어 허용을 지원하여 다국어 콘텐츠를 가져올 수 있습니다. 방문자가 항상 사이트의 기존 콘텐츠로 이동할 수 있도록 언어별로 대체 언어를 지정할 수도 있습니다.

## 라우팅 로직

Astro는 [미들웨어](/ko/guides/middleware/)를 사용하여 라우팅 로직을 구현합니다. 이 미들웨어 함수는 최종적으로 자체 로직을 실행하기 전에 추가 미들웨어 및 각 페이지 경로에서 나오는 모든 `Response`을 기다리는 [첫 번째 위치](/ko/guides/middleware/#미들웨어-체이닝)에 배치됩니다.

이는 자체 미들웨어 및 페이지 로직의 작업 (예: 리디렉션)이 먼저 실행되고 경로가 렌더링된 다음 i18n 미들웨어가 현지화된 URL이 유효한 경로에 해당하는지 확인하는 등의 자체 작업을 수행함을 의미합니다.

[Astro의 i18n 미들웨어에 추가하거나 대신에 자신만의 i18n 로직을 추가](#manual)하도록 선택할 수도 있습니다. 그러면 `astro:i18n` 도우미 함수에 계속 액세스하면서 경로를 더욱 효과적으로 제어할 수 있습니다.

## i18n 라우팅 구성

지원되는 모든 언어 목록([`locales`](/ko/reference/configuration-reference/#i18nlocales))과 `locales`에 나열된 언어 중 하나여야 하는 기본 언어([`defaultLocale`](/ko/reference/configuration-reference/#i18ndefaultlocale))를 `i18n` 구성 객체에 지정해야 합니다. 또한 더 구체적인 라우팅과 원하는 URL에 맞게 대체 동작을 구성할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "pt-br"],
    defaultLocale: "en",
  }
})
```

### 현지화된 폴더 생성

언어별로 현지화된 콘텐츠로 콘텐츠 폴더를 구성하세요. `src/pages/` 내 어디에든 개별 `/[locale]/` 폴더를 생성하면 Astro의 [파일 기반 라우팅](/ko/guides/routing/)이 해당 URL 경로에 페이지를 생성합니다.

폴더 이름은 `locales` 항목과 정확히 일치해야 합니다. 기본 언어에 대한 현지화된 URL 경로 (예: `/en/about/`)를 표시하도록 `prefixDefaultLocale: true`를 구성한 경우에만 `defaultLocale`에 대한 현지화된 폴더를 포함합니다.

<FileTree>
- src
  - pages
    - about.astro
    - index.astro
    - es
      - about.astro
      - index.astro
    - pt-br
      - about.astro
      - index.astro
</FileTree>

:::note
현지화된 폴더가 반드시 `/pages/` 폴더의 루트에 있을 필요는 없습니다.
:::

### 링크 생성

i18n 라우팅이 구성되면 이제 [`astro:i18n` 모듈](/ko/reference/modules/astro-i18n/)에서 사용할 수 있는 [`getRelativeLocaleUrl()`](/ko/reference/modules/astro-i18n/#getrelativelocaleurl)과 같은 도우미 함수를 사용하여 사이트 내 페이지에 대한 링크를 계산할 수 있습니다. 생성된 링크는 항상 정확하고 현지화된 경로를 제공하며 사이트에서 URL을 올바르게 사용하거나 확인하는 데 도움이 될 수 있습니다.

링크를 수동으로 작성할 수도 있습니다.

```astro title="src/pages/es/index.astro"
---
import { getRelativeLocaleUrl } from 'astro:i18n';
// defaultLocale는 "es"입니다.
const aboutURL = getRelativeLocaleUrl("es", "about");
---
<a href="/get-started/">¡Vamos!</a>
<a href={getRelativeLocaleUrl("es", 'blog')}>Blog</a>
<a href={aboutURL}>Acerca</a>
```

## `routing`

Astro의 내장 파일 기반 라우팅은 `src/pages/` 내 파일 구조를 기반으로 URL 경로를 자동으로 생성합니다.

i18n 라우팅을 구성하면 이 파일 구조 (및 생성된 해당 URL 경로)에 대한 정보를 i18n 도우미 함수에서 사용할 수 있으므로 프로젝트에서 경로를 생성, 사용 및 확인할 수 있습니다. 더 많은 사용자 정의 및 언어별 유연성을 위해 이러한 옵션 중 다수를 함께 사용할 수 있습니다.

더 강력한 제어를 위해 [자신만의 라우팅 로직을 수동으로 구현](#manual)할 수도 있습니다.

### `prefixDefaultLocale`

<p><Since v="3.5.0" /></p>

이 라우팅 옵션은 기본 언어의 URL이 언어 접두사 (예: `/en/about/`)를 사용해야 하는지 여부를 정의합니다.

기본이 아닌 모든 지원 언어는 지역화된 접두사 (예: `/fr/` 또는 `/french/`)를 사용하며 콘텐츠 파일은 적절한 폴더에 있어야 합니다. 이 구성 옵션을 사용하면 기본 언어도 지역화된 URL 구조를 따라야 하는지 여부를 지정할 수 있습니다.

또한 이 설정은 파일 구조와 URL 구조가 모든 언어에 대해 일치해야 하므로 기본 언어에 대한 페이지 파일이 존재해야 하는 위치 (예: `src/pages/about/` 또는 `src/pages/en/about`)를 결정합니다.

- `"prefixDefaultLocale: false"` (기본값): 기본 언어로 된 URL에는 `/[locale]/` 접두사가 **없습니다**. 다른 모든 로케일에는 적용됩니다.

- `"prefixDefaultLocale: true"`: 기본 언어를 포함한 모든 URL에는 `/[locale]/` 접두사가 붙습니다.

#### `prefixDefaultLocale: false`

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: {
      prefixDefaultLocale: false,
    },
  },
});
```

이것이 **기본값**입니다. 기본 언어의 URL에 `/[locale]/` 접두사가 **없으며** 기본 언어의 파일이 `src/pages/` 루트에 존재하는 경우 이 옵션을 설정하세요.

<FileTree>
  - src
    - pages
      - about.astro
      - index.astro
      - es
        - about.astro
        - index.astro
      - fr
        - about.astro
        - index.astro
</FileTree>

- `src/pages/about.astro`는 `example.com/about/` 경로를 생성합니다.
- `src/pages/fr/about.astro`는 `example.com/fr/about/` 경로를 생성합니다.

#### `prefixDefaultLocale: true`

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: {
      prefixDefaultLocale: true,
    },
  },
});
```

모든 경로의 URL에 `/locale/` 접두사가 있고 `defaultLocale`에 대한 파일을 포함한 모든 페이지 콘텐츠 파일이 현지화된 폴더에 있는 경우 이 옵션을 설정하세요.

    <FileTree>
    - src
      - pages
        - **index.astro** // 참고: 이 파일은 항상 필요합니다.
        - en
          - index.astro
          - about.astro
        - es
          - about.astro
          - index.astro
        - pt-br
          - about.astro
          - index.astro
    </FileTree>

- 로케일 접두사가 없는 URL (예: `example.com/about/`)은 [대체 전략](#대체하기)을 지정하지 않는 한 404 (찾을 수 없음) 상태 코드를 반환합니다.

### `redirectToDefaultLocale`

<p>
  <Since v="4.2.0" />
</p>

`src/pages/index.astro`에 의해 생성된 홈 URL (`/`)이 `/<defaultLocale>`로 리디렉션되는지 여부를 구성합니다.

`prefixDefaultLocale: true`를 설정하면 `routing` 구성 객체에서 `redirectToDefaultLocale: true`도 자동으로 설정됩니다. 기본적으로 필수 `src/pages/index.astro` 파일은 자동으로 기본 로케일의 인덱스 페이지로 리디렉션됩니다.

[`redirectToDefaultLocale: false` 설정](/ko/reference/configuration-reference/#i18nroutingredirecttodefaultlocale)을 통해 이 동작을 선택 해제할 수 있습니다. 이를 통해 구성된 로케일 폴더 구조 외부에 존재하는 사이트 홈 페이지를 가질 수 있습니다.

### `manual`

<p><Since v="4.6.0" /></p>

이 옵션이 활성화되면 Astro는 사용자 정의 로직을 구현할 수 있도록 i18n 미들웨어를 **비활성화**합니다. 다른 `routing` 옵션 (예: `prefixDefaultLocale`)은 `routing: "manual"`으로 구성할 수 없습니다.

여러분은 자신만의 라우팅 로직을 작성하거나 [Astro의 i18n 미들웨어를 수동으로 실행](#미들웨어-함수)할 책임이 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: "manual"
  }
})
```

Astro는 미들웨어를 위한 도우미 함수를 제공하므로 기본 라우팅, 예외, 대체 동작, 오류 캐치 등을 제어할 수 있습니다: [`redirectToDefaultLocale()`](/ko/reference/modules/astro-i18n/#redirecttodefaultlocale), [`notFound ()`](/ko/reference/modules/astro-i18n/#notfound) 및 [`redirectToFallback()`](/ko/reference/modules/astro-i18n/#redirecttofallback):

```js title="src/middleware.js"
import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n"; // 'manual' 라우팅으로 사용 가능한 함수
export const onRequest = defineMiddleware(async (ctx, next) => {
  if (ctx.url.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(302);
  }
})
```

#### 미들웨어 함수

[`middleware`](#미들웨어-함수) 함수는 Astro의 i18n 미들웨어를 수동으로 생성합니다. 이를 통해 Astro의 i18n 라우팅을 완전히 교체하는 대신 확장할 수 있습니다.

순서를 결정하기 위해 [`sequence`](/ko/reference/modules/astro-middleware/#sequence) 유틸리티를 사용하여 자체 미들웨어와 함께 [라우팅 옵션](#routing)과 함께 `middleware`를 실행할 수 있습니다.

```js title="src/middleware.js"
import {defineMiddleware, sequence} from "astro:middleware";
import { middleware } from "astro:i18n"; // Astro의 자체 i18n 라우팅 구성

export const userMiddleware = defineMiddleware(async (ctx, next) => {
  // 이 response는 Astro의 i18n 미들웨어에서 나올 수 있으며 404를 반환할 수 있습니다.
  const response = await next();
  // /about 페이지는 예외이므로 렌더링하고 싶습니다.
  if (ctx.url.startsWith("/about")) {
    return new Response("About page", {
      status: 200
    });
  } else {
    return response;
  }
});

export const onRequest = sequence(
  userMiddleware,
  middleware({
    redirectToDefaultLocale: false,
    prefixDefaultLocale: true
  })
)
```

## `domains`

<p><Since v="4.9.0" /></p>

이 라우팅 옵션을 사용하면 `site`가 구성된 [`@astrojs/node`](/ko/guides/integrations-guide/node/) 또는 [`@astrojs/vercel`](/ko/guides/integrations-guide/vercel/) 어댑터를 사용하여 `server` 렌더링 프로젝트에 대해 언어별로 도메인을 사용자 정의할 수 있습니다.

지원되는 `locales`를 맞춤 URL에 매핑하려면 `i18n.domains`를 추가하세요.

```js title="astro.config.mjs" {3-7} ins={14-17}
import { defineConfig } from "astro/config"
export default defineConfig({
  site: "https://example.com",
  output: "server", // 사전 렌더링된 페이지가 없는 경우 필수
  adapter: node({
    mode: 'standalone',
  }),
  i18n: {
    locales: ["es", "en", "fr", "ja"],
    defaultLocale: "en",
    routing: {
      prefixDefaultLocale: false
    },
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es"
    }
  },
  experimental: {
    i18nDomains: true
  }
})
```

매핑되지 않은 모든 `locales`은 `prefixDefaultLocales` 구성을 따릅니다. 그러나 이 값이 `false`인 경우에도 `defaultLocale`에 대한 페이지 파일은 현지화된 폴더 내에 있어야 합니다. 위 구성을 위해서는 `/en/` 폴더가 필요합니다.

위 구성을 사용하면 다음과 같습니다.

- `/fr/about.astro` 파일은 `https://fr.example.com/about`의 URL을 생성합니다.
- `/es/about.astro` 파일은 `https://example.es/about`의 URL을 생성합니다.
- `/ja/about.astro` 파일은 `https://example.com/ja/about`의 URL을 생성합니다.
- `/en/about.astro` 파일은 `https://example.com/about`의 URL을 생성합니다.

위 URL은 `getAbsoluteLocaleUrl()` 및 `getAbsoluteLocaleUrlList()` 함수에서도 반환됩니다.

## 대체하기

한 언어로 된 페이지가 존재하지 않는 경우 (예: 아직 번역되지 않은 페이지), 404 페이지를 표시하는 대신 언어별로 다른 `locale`의 대체 콘텐츠를 표시하도록 선택할 수 있습니다. 이는 아직 모든 경로에 대한 페이지가 없지만 방문자에게 일부 콘텐츠를 제공하려는 경우에 유용합니다.

대체 전략은 두 부분으로 구성됩니다. 어떤 언어를 다른 언어로 대체할지 선택하는 것 ([`i18n.fallback`](/ko/reference/configuration-reference/#i18nfallback))과 대체 콘텐츠 (Astro v4.15.0에서 추가된 [`i18n.routing.fallbackType`](/ko/reference/configuration-reference/#i18nroutingfallbacktype))를 표시하기 위해 [리디렉션](/ko/guides/routing/#리디렉션)을 수행할지 아니면 [리라이트](/ko/guides/routing/#url-재작성-rewrites)를 수행할지 선택하는 것입니다.

예를 들어, `i18n.fallback: { fr: "es" }`를 구성하면, Astro는 `src/pages/es/`에 존재하는 모든 페이지에 대해 `src/pages/fr/`에 페이지가 빌드되도록 합니다.

페이지가 아직 존재하지 않으면 `fallbackType`에 따라 페이지가 생성됩니다:

- 해당 `es` 경로로 리디렉션합니다 (기본 동작).
- `/es/` 페이지의 콘텐츠 (`i18n.routing.fallbackType: "rewrite"`)를 사용합니다.

예를 들어, 아래 구성은 누락된 `fr` 경로에 대한 대체 로케일로 `es`를 설정합니다. 즉, `example.com/fr/my-page/`를 방문하는 사용자는 `src/pages/fr/my-page.astro`가 없는 경우 404 페이지로 이동하는 대신 리디렉션되지 않고 `example.com/es/my-page/`의 콘텐츠를 보게 됩니다.

```js title="astro.config.mjs" ins={6-8,10}
import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    fallback: {
      fr: "es"
    },
    routing: {
      fallbackType: "rewrite"
    }
  }
})
```

## 사용자 정의 로케일 경로

사이트에서 지원되는 `locales`를 문자열 (예: "en", "pt-br")로 정의하는 것 외에도 Astro를 사용하면 [브라우저에서 인식할 수 있는 임의 개수의 언어 `codes`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Accept-Language)를 사용자 정의 URL `path`에 매핑할 수 있습니다. locales는 프로젝트 폴더 구조에 해당하는 한 모든 형식의 문자열이 될 수 있지만 `codes`는 브라우저에서 허용되는 구문을 따라야 합니다.

맞춤 URL 접두사를 정의하려면 `path` 키를 사용하여 `locales` 배열에 객체를 전달하고, 이 URL에 매핑된 언어를 나타내는 `codes`를 전달합니다. 이 경우 `/[locale]/` 폴더 이름은 `path` 값과 정확히 일치해야 하며 URL은 `path` 값을 사용하여 생성됩니다.

이는 언어의 여러 변형 (예: `"fr"`, `"fr-BR"`, `"fr-CA"`)을 지원하고 이러한 모든 변형을 동일한 URL `/fr/` 아래에 매핑하거나 사용자 정의하려는 경우에 유용합니다. (예: `/french/`):

```js title="astro.config.mjs" del={4} ins={5-8}
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["es", "en", "fr"],
    locales: ["es", "en", {
      path: 'french', // 슬래시가 포함되지 않음
      codes: ["fr", "fr-BR", "fr-CA"],
    }],
    defaultLocale: "en",
    routing: {
      prefixDefaultLocale: true,
    },
  },
});
```

[`astro:i18n` 가상 모듈](/ko/reference/modules/astro-i18n/)의 함수를 사용하여 구성 (예: `getRelativeLocaleUrl()`)에 따라 유효한 URL 경로를 계산하는 경우, [해당 `path`를 `locale` 값으로 사용](/ko/reference/modules/astro-i18n/#getlocalebypath)하세요.

#### 제한 사항

이 기능에는 몇 가지 제한사항이 있습니다.

- `site` 옵션은 필수입니다.
- `output` 옵션은 `"server"`로 설정되어야 합니다.
- 사전 렌더링된 개별 페이지는 있을 수 없습니다.

Astro는 이 기능을 지원하기 위해 다음 헤더를 사용합니다.
- [`X-Forwarded-Host`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/X-Forwarded-Host) 및 [`Host`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Host). Astro는 전자를 사용하고, 없을 경우 후자를 시도합니다.
- 서버 요청의 [`X-Forwarded-Proto`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/X-Forwarded-Proto) 및 [`URL#protocol`](https://developer.mozilla.org/ko/docs/Web/API/URL/protocol).

서버 프록시/호스팅 플랫폼이 이 정보를 제공할 수 있는지 확인하세요. 이러한 헤더를 검색하지 못하면 404 (상태 코드) 페이지가 표시됩니다.

## 브라우저 언어 감지

Astro의 [주문형 서버 렌더링 모드 (`output:'server'` 또는 `output:'hybrid'`)](/ko/guides/on-demand-rendering/) 중 하나와 결합된 Astro의 i18n 라우팅을 사용하면 브라우저 언어 감지를 위한 두 가지 속성인 `Astro.preferredLocale` 및 `Astro.preferredLocaleList`에 액세스할 수 있습니다.

이는 브라우저의 `Accept-Language` 헤더와 `locales` (문자열 또는 `codes`)를 결합하여 방문자가 선호하는 언어를 자동으로 적용합니다.

- [`Astro.preferredLocale`](/ko/reference/api-reference/#preferredlocale): Astro는 브라우저의 선호 언어가 `locales` 배열에 포함된 경우, 방문자를 위한 **선호 언어**를 계산할 수 있습니다. 일치 항목이 없으면 이 값은 undefined가 됩니다.
- [`Astro.preferredLocaleList`](/ko/reference/api-reference/#preferredlocalelist): 브라우저에서 요청하고 웹사이트에서 지원하는 모든 언어의 배열입니다. 그러면 여러분의 사이트와 방문자 간 호환되는 모든 언어 목록이 생성됩니다. 브라우저가 요청한 언어가 `locales` 배열에 없으면 값은 `[]`입니다. 브라우저가 기본 언어를 지정하지 않으면 이 값은 [`i18n.locales`]가 됩니다.
- [`Astro.currentLocale`](/ko/reference/api-reference/#currentlocale): `locales` 구성에 지정된 구문을 사용하여 현재 URL에서 계산된 언어입니다. URL에 `/[locale]/` 접두사가 포함되어 있지 않으면 값은 기본적으로 `i18n.defaultLocale`이 됩니다.

방문자의 선호도를 성공적으로 일치시키려면 [브라우저에서 사용하는 것](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Accept-Language)과 동일한 패턴을 사용하여 `codes`를 제공하십시오.

[`site`]: /ko/reference/configuration-reference/#site
[`i18n.locales`]: /ko/reference/configuration-reference/#i18nlocales
